Cream of the Crop 1

home *** CD-ROM | disk | FTP | other *** search

/ Cream of the Crop 1 / Cream of the Crop 1.iso / PROGRAM / ICNDRW_1.ARJ / ICONDRAW.DOC < prev next >

Wrap

Text File | 1991-09-01 | 60KB | 1,227 lines

╔═════════════════════════════════════════════╗ ║ ICON DRAW version 1.0 ║ ║ Copyright (c) 1991 - SofDesign Technology ║ ║ All Rights Reserved ║ ║ ║ ║ SofDesign Technology ║ ║ 58 North Dillon Dr. ║ ║ Titusville, PA 16354-2406 ║ ╚═════════════════════════════════════════════╝ DISCLAIMER OF WARRANTY THIS SOFTWARE IS PROVIDED WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES WHATSOEVER. BECAUSE OF THE DIVERSITY OF CONDITIONS AND HARDWARE UNDER WHICH THIS SOFTWARE MAY BE USED, NO WARRANTY OF FITNESS FOR A PARTICULAR PURPOSE IS OFFERED. THE USER IS ADVISED TO TEST THIS SOFTWARE THOROUGHLY BEFORE RELYING ON IT. THE USER MUST ASSUME THE ENTIRE RISK OF USING THIS SOFTWARE. This program, library and documentation were written by Thomas J. Clancy, Jr. of SofDesign Technology. Turbo Pascal is a registered trademark of Borland International. Microsoft Windows is a registered trademark of Microsoft Corporation. SHAREWARE NOTICE This software and manual are shareware and may be freely copied and distributed, and may be used for a trial basis of only thirty days. If you decide that this product is worth keeping then it must be registered to the author. Included is an order form which is to be filled out and returned to the author with payment. If you have received this product through a User's Group, Software Library, or SIG, and have paid a small fee, you have NOT acquired the registration rights to this product. You may NOT charge any fee for this product (program or documentation) without our written consent. You may NOT distribute this product (program or documentation) in connection with any commercial venture, product, publication, or service without our written approval. Table of Contents Chapter Page # 1 INTRODUCING ICON DRAW VERSION 1.0 .........................1 1.2 Why Use ICON DRAW? .................................1 1.3 What You Should Find ...............................2 1.4 What You Need in Order to Run Icon Draw ............2 2 INSTALLING ICON DRAW ......................................3 2.1 Hard Drive Owners ..................................3 2.2 For Floppy Only Users ..............................3 3 USING ICON286 .............................................4 3.1 The Environment ....................................4 3.1.1 Icon Pane ....................................5 3.1.2 Status Pane ..................................5 3.1.3 Editing Grid .................................5 3.1.4 Tool Pane ....................................5 3.1.5 Menu Bar .....................................6 3.1.5.1 Quitting .............................6 3.1.5.2 Saving Icons .........................6 3.1.5.3 Loading Icons ........................6 3.1.5.4 New ..................................7 3.1.5.5 Getting Help .........................7 3.1.5.6 Graphics Mode ........................7 3.1.5.7 About ................................7 4 USING THE PROGRAMMER'S LIBRARY ............................8 4.1 An Introduction to Objects .........................8 4.2 Getting Started with a Simple Program .............10 4.3 Moving Up to the Mouse ............................12 5 ICON286 Supplementary Tools and Other Programs ...........15 5.1 ICON286 Library Manager ...........................15 5.1.1 Using Libraries with Icon Tools .............15 5.1.2 Making Libraries for Multiple Adapters ......16 5.2 Using CNVICON.EXE .................................16 5.3 Making Animation Libraries ........................17 5.4 TLIST the File Lister .............................17 6 CLOSING NOTES/TECHNICAL STUFF ............................19 6.1 Closing Notes .....................................19 6.2 Future Notes ......................................19 Chapter 1 -- INTRODUCING ICON DRAW VERSION 1.0 Welcome to ICON DRAW version 1.0, the graphical icon drawing tool and programmer's library that allows Turbo Pascal 6.0 programmers to create and manipulate icons within their own GUIs. Note that this is NOT a Microsoft Windows product and the icons and related programming libraries are incompatible with any version of Microsoft Windows. But you can write your own GUI that utilizes the icons you create, and who knows? Your product may be the next rival of Microsoft Windows 3.0, giving them a run for their money. ICON DRAW comes with two versions of the program, ICON88 and ICON286. Both are functionally the same, but ICON88 will work with all machines, including slow PC's and XT's. ICON286 will work with AT compatible machines and better. Also with ICON DRAW is source code for ICONTOOLS, an object oriented library of routines for manipulating icons that you create with ICON DRAW. There is also some example source code that shows you how to use ICONTOOLS effectively in a Turbo Pascal 6.0 program. And because the library is object oriented, it's extensible, which means you can create your own objects that will handle icons in whatever kind of environment or program you're producing. 1.2 Why Use Icon Draw? The reason that ICON DRAW was originally developed was to be able to use icons in graphically oriented programs. I was, at one time during my naive days, trying to write my own version of Microsoft Windows 2.01. When I got only so far with the project, and after basically burning myself out, I gave up the entire idea completely and concentrated on different sorts of things. But when Microsoft came out with Windows 3.0 my interest in a graphically oriented environment slowly took shape again. I liked Microsoft's whole knew look, especially the icons. I didn't necessarily have in mind writing a Windows-like environment, but I wanted to have the tools so I'd be able write simple GUIS for certain applications I had in mind, and since graphics programming opens up a whole knew realm of potential, I wanted to be able to have certain controlled functionality when attempting a graphically oriented project. Finally, one cold day in my dormitory room, sneezing, wheezing, and coughing from a terrible cold, ICON TOOLS and ICON DRAW were born, and I was able to create programs that used icons. Unfortunately I only owned a Tandy 1000 sx computer and didn't have the advantage of an EGA or VGA, so my graphics programs weren't as snazzy as they could have been, but when writing ICON DRAW and ICON TOOLS I had access, through some friends and the school's computer room, to 286 and 386 based computers with EGA and VGA monitors and was able to test ICON DRAW and make wonderfully colorful, 3-D looking icons. So, you can do the same thing with whatever kind of graphics adapter you have as long as it is capable of doing graphics (text-only monochrome adapters will not work with this program. If you have monochrome then it should be a hercules compatible graphics adapter). - 1 - 1.3 What You Should Find You should find the following files with ICON DRAW: ICON88.EXE - The 8088 version of ICON DRAW. ICON286.EXE - The 80286 version of ICON DRAW. ILIB.EXE - An Icon library manager. TLIST.EXE - File viewer (free of charge). CNVICON.EXE - Converts .ICS files to .ICN files for your monitor. ICONDRAW.DOC - ICON DRAW manual. REGISTER.DOC - Registration form to be filled out and returned to SofDesign Technology. BUGSHEET.DOC - Can be filled out and returned if you discover any bugs you'd like to report. PRODUCTS.TXT - An updated list of products available through SofDesign. NEW.BAT - Launches file viewer so you can view and print the new products listing. README.BAT - Launches file viewer so you can view and print the manual. SOURCE.ZIP - Various Pascal programs including programmer's library source. ALIEN.ZIP - A simple alien space game using the icon library routines. Files included with SOURCE.ZIP: TESTICON.PAS - Sample program that loads 255 icons, then rapidly displays and removes them in succession. CNVICON.PAS - The source for CNVICON.EXE. GRAFINIT.PAS - Include file useful for initializing graphics adapters. ANIMAT.PAS - Sample program that demonstrates how you can use an icon library as an animation file. DRAGICON.PAS - Sample program that demonstrates dragging an icon with the mouse. MOUSE.PAS - Source code for the mouse interface library. This works with Microsoft Compatible mice. MOUSE.TPU - TPU format for MOUSE.PAS ICONTOOL.PAS - The object oriented programmer's library. ICONTOOL.TPU - TPU format for ICONTOOL.PAS. 1.4 What You Need in Order to Run Icon Draw To run ICON DRAW you will need any IBM PC/XT/AT compatible computer with any kind of graphics adapter from Hercules to standard VGA. You will also need at least 512k of memory and a Microsoft compatible mouse. A hard disk is strongly recommended, and you will need Turbo Pascal 6.0 or a compatible compiler to use the programmer's library in order to use the icons you create. - 2 - Chapter 2 -- INSTALLING ICON DRAW: You can find ICON DRAW a number of ways, but the most likely place is on a BBS. If you have downloaded this from a BBS then follow these instructions for preparing ICON DRAW to work with what you have. 2.1 Hard Drive Owners I'm going to assume, or hope, that you have a hard drive, and if you do, then you should create a subdirectory on your hard drive calling it ICONDRAW (or whatever name suits your taste). Uncompress the ICON286 archive in whatever format it has been archived under into the subdirectory you just created. You should have all the files that I have listed above. In case your archive is missing some of the files, please write us here at SofDesign Technology, or call if you like, and we will send you the necessary files that are missing. You can also unarchive the ALIEN.ZIP file and the SOURCE.ZIP file and look at what you've got. Both these archives will be explained later. 2.2 For Floppy Only Users: If you have a floppy drive system, uncompress the files to a freshly formatted disk. Since Turbo Pascal 6.0 is recommended for working on a hard drive, and in fact I think it needs to be run from a hard drive, then there is little point in using this product without a hard drive. You can still use it, however, on a floppy based system to create icons since icon source and binary files take up little space. You can then transport the icon files to a system that has Turbo Pascal 6.0 on it and use the icon binary files to include in any kind of graphics based program you may be writing. - 3 - Chapter 3 -- USING ICON286 For the remainder of the manual I will refer to ICON DRAW as ICON286 since it was originally intended to run on my pitifully slow Tandy 1000 sx with it's pitifully slow (though somewhat faster) 286 accelerator card. And since I needed all the speed I could get, I relied on Turbo Pascal's 286 instruction set feature to squeeze a little more speed out of my machine. First things first. Once you've installed ICON286 onto your system, then you're ready to begin. If you have an old PC or an XT, that is, if you have a computer with an 8088 or an 8086 microprocessor, then you need to run the ICON88.EXE program. Any other type of IBM compatible computer with an 80286 or higher microprocessor can run the ICON286.EXE program. There is nothing functionally different about the two programs. The ICON286 program, because it uses the 80286 instruction set, is slightly smaller and faster, which is the advantage of having an AT or better computer. When you have determined which one you need to run, then run the program and take a look. Make sure you have a Microsoft compatible mouse since there is no way of using the icon draw program without one. All the push buttons are activated with the mouse and the drawing grid works only with a mouse. 3.1 The Environment The ICON286 environment is set up with four window panes and a set of push buttons on the bottom of the screen that act as a menu. The following is a representational diagram of the ICON286 environment: ┌──────────────┬───────────────────────────────────┬────────────┐ │ Icon │ │ Tools │ │ │ │ │ │ │ │ S B C B │ │ │ │ I u O u │ │ │ │ Z t L t │ │ │ │ E t O t │ │ │ │ o R o │ ├──────────────┤ │ n n │ │Grid: 30 x 25 │ Grid Area │ s s │ │X: │ │ │ │Y: │ │ │ │ │ │ S B │ │Drawing Color │ │ H u │ │┌────────────┐│ │ I t │ ││ ││ │ F t │ ││ ││ │ T o │ │└────────────┘│ │ n │ │Size Ratio: 1 │ │ s │ │ │ │ │ └──────────────┴───────────────────────────────────┴────────────┘ ┌─────────────────────────────────────────────────────────┐ │ Quit Save Load New Help Fill Graphics Mode About │ └─────────────────────────────────────────────────────────┘ - 4 - 3.1.1 Icon Pane: Pane 1 is the ICON window pane. This pane will display the icon as it's being drawn so you can see the progress of what's happening and how it will look on your screen. Because the Grid is an approximation of the icon, it will sometimes look wider or longer than the actual icon, depending on the grid size, so the ICON pane was provided for convenience sake. 3.1.2 Status Pane: Pane 2, or the status pane, which is directly below the ICON pane, contains status information about what's currently going on in ICON286. The GRID: indicator displays what the icons size currently is. 30 x 25 is the default setting when first loading ICON286. When you create and save an icon in a particular grid size, then ICON286 will load and size the grid automatically to the saved icon's length and width. The X: and Y: indicators display where your mouse is on the grid relative to the grid coordinates. The drawing color bar displays which drawing color is currently in use by the program. The SIZE RATIO indicates how many blocks the grid will grow or shrink when resizing the window with the SIZE PUSH BUTTONS. To set the size of the ration, 1 through 9, press whichever number on your keyboard you wish the RATIO to be when sizing. 3.1.3 Editing Grid Pane: The third pane, the largest pane in the environment, contains the drawing grid. To draw within the grid, place the mouse pointer on the grid where you want to start drawing, depress the LEFT mouse button, and start moving. The magnified blocks will turn the color of the current drawing color. To erase a particular block or sequence of blocks, hold down the RIGHT mouse button and begin drawing over the place you want erased. This has the same effect as choosing black as a drawing color and drawing with it. 3.1.4 Tool Pane: The fourth pane contains various push button tools. The first set is the grid SIZE buttons. You have four choices. You can shrink the size of the grid vertically with the UP ARROW button, you can increase the size vertically with the DOWN ARROW button, you can increase the size horizontally with the RIGHT ARROW button and decrease the grid horizontally with the LEFT ARROW button. The grid will decrease or increase by the number of blocks specified in the SIZE RATIO indicator in the status - 5 - window. The second set of push buttons is the SHIFT BUTTONS. These buttons will shift an image within the grid up, down, left or right depending on which button you push (the arrows correspond to the direction). When an image reaches an edge, up, down, left or right, it will simply wrap to the other side. The grids maximum capacity is 50 x 50, so when the image reaches 50 on the right or on the bottom, part of it wraps around starting at one. If the grid is set to 30 x 25 and you shift your image left or right, then the image will just go off the screen because it's being shifted within the 50 x 50 grid. The color buttons allow you to select which drawing color you want to use. When you select a color, the DRAWING COLOR block in the Status window changes accordingly. 3.1.5 The Menu Bar: The menu bar across the bottom works the same way the other buttons work. But you can also choose the first letter of each option via the keyboard and that function will be performed as if you pushed the button with the mouse. 3.1.5.1 Quitting: The QUIT pushbutton needs no explanation. But when you push that button, you are asked if you really want to quit. This is obviously a safeguard from accidently choosing quit. 3.1.5.2 Saving Icons: The SAVE option lets you save the icon you're currently creating or editing. When pushed, a prompt appears asking you for an eight letter name that is used by DOS. Then a second prompt appears asking you for an extended name which is saved within the icon file. The extended name can be used within your applications and is explained later (see the Programming Library chapter for more details). When you save an icon, ICON286 generates two files. One is an ICS file that contains the source for the icon that ICON286 loads and interprets. The other file is an ICN bit mapped file that the Pascal Library uses and that you will use when creating applications with your icons. ICON286 can't read the ICN files directly, so make sure you don't lose the ICS source files or else you won't be able to go back and edit your icons. 3.1.5.3 Loading Icons: Loading icons is similar to saving. A prompt asks you for the eight letter icon file name, and if it finds the appropriate icon source file, it will load and display it so you can edit it. - 6 - 3.1.5.4 New (Clearing the Work Space): Using the new option erases your work space and allows you to begin again. It saves the grid size you were currently working with, so if you want a new grid size then you'll have to size it manually. I found, though, that when creating a library of icons, I was usually using the same icon size. Whenever I'd push NEW, I'd want to keep the grid size I was previously working with so I didn't have to keep sizing the grid to whatever I desired. 3.1.5.5 Getting Help: There is a simple built-in help window that pops up when you choose the help option. It simply displays and briefly explains what the different function are and what they do. It also explains what you can do with the mouse and what keys do what. 3.1.5.6 Graphics Mode: When this option is selected, a popup window appears allowing you to choose, with a mouse, which graphics mode you'd like to work in. BE CAREFUL with this option. If you don't support a certain mode and go ahead and choose it anyway, then your screen will go blank. The program will still function properly in most cases so all you'll need to do is press Q and Y to quit the program. This saves from having to reboot the computer if you think your machine froze. Some graphics modes have extended options and another popup menu will appear displaying what resolutions there are under a certain graphics adapter. Pressing the mouse button OFF the menu will simply make the menu go away. This is in case you change your mind and don't want to change the graphics mode. 3.1.5.7 About: This screen just displays a copyright notice with the author's name (me) and the version number. Pressing the LEFT mouse button removes the message. - 7 - Chapter 4 -- USING THE PROGRAMMER'S LIBRARY 4.1 An Introduction to the Objects The programmer's library is a set of Turbo Pascal 6.0 objects for loading and manipulating icons created with ICON286. I've provided all the source code, not just the object headers, so you can see how I manipulate the icons and also to be able to more effectively extend the objects to your taste. Here is the object source headers as I have defined them in Turbo Pascal 6.0. Study them, follow the next few section, and soon you'll be writing your own icon based applications. icon = object x,y : integer; theicon : icon_record; error : boolean; put_type : word; titleon : boolean; hidden : boolean; libheader : header_type; boundaries : icon_window; procedure init(iconlib:string; iconfile:string; startx,starty: integer); function initerror:boolean; function inbounds(mx,my:integer):boolean; function is_hidden:boolean; function is_showing:boolean; function get_length:integer; function get_height:integer; function getx:integer; function gety:integer; function gettop:integer; function getleft:integer; function getbottom:integer; function getright:integer; procedure setboundaries(x1,y1,x2,y2:integer); procedure showicon; procedure hideicon; procedure icontitle(on:boolean); procedure setput(put:word); procedure setxy(newx,newy:integer); procedure moveicon(newx,newy:integer); procedure mousedragicon(onbutton:word); procedure display_icon; procedure disposeicon; procedure done; private image_behind : pointer; icon_image : pointer; title_image : pointer; size, size_title_image : longint; procedure get_rear_image; procedure get_title_image; - 8 - procedure dispose_rear_image; procedure dispose_title_image; end; icon_manager = object(icon) icons : array [1..500] of ^icon; numicons : integer; mboundaries : icon_window; procedure init(left,top,bottom,right:integer); procedure addicon(iconlib:string; iconfile:string; startx,starty: integer; put:word; t:boolean); function initerror(i:integer):boolean; function inbounds(i:integer; mx,my:integer):boolean; function onwhichicon(mx,my:word):integer; function is_hidden(i:integer):boolean; function is_showing(i:integer):boolean; function get_length(i:integer):integer; function get_height(i:integer):integer; function getx(i:integer):integer; function gety(i:integer):integer; function gettop(i:integer):integer; function getleft(i:integer):integer; function getbottom(i:integer):integer; function getright(i:integer):integer; function currenticon:integer; function withinboundaries(mx,my:integer):boolean; procedure setmanagerboundaries(x1,y1,x2,y2:integer); procedure setboundaries(i,x1,y1,x2,y2:integer); procedure showicon(i:integer); procedure hideicon(i:integer); procedure icontitle(i:integer; on:boolean); procedure setput(i:integer; put:word); procedure setxy(i:integer; newx,newy:integer); procedure moveicon(i:integer; newx,newy:integer); procedure mousedragicon(onbutton:word); procedure display_icon(i:integer); procedure disposeicon(i:integer); procedure showallicons; procedure hideallicons; procedure disposeallicons; procedure done; end; There are two objects, one is the ICON object itself and the other is an ICON MANAGER object that will manage up to 500 icons. Of course you can always declare more than one icon manager and have even more icons and so on until you run out of memory. The icon manager object is limited in what it can do, but with some innovative programming, you can create an icon manager that is event driven and that will effectively manage icons with multiple overlapping and redrawing. That's one of the wonderful things about object oriented programming, the extensibility of it all! - 9 - 4.2 Getting Started with a Simple Program If you're unfamiliar with programming graphics in Turbo Pascal, then you should read the sections in your manual that deal with graphics programming. There are two ways of using the graphics drivers that come with Turbo Pascal. One way is to keep the drivers and font files in the directory that your executable application is in, but then you have all the overhead of having extra files that could be lost or damaged. The second way is to run the MAKE program on the BGILINK.PAS file. This will create two files, BGIDRIV.TPU and BGIFONT.TPU. These can then be linked into your program, though significantly adding to the size of your executable, but giving the user you're creating the program for the flexibility to go from one type of graphics adapter to another. I'm going to show all my demonstrations using the second technique because I think it's the best way to go when creating graphics applications. I've included a Microsoft Compatible Mouse Driver unit, source too, for use with programming your icons with a mouse. Since the library requires a mouse (though you can create an object that will work with keyboard as well) I will keep to the mouse format from here on. If you have a different sort of mouse and an appropriate interface library, or if you have another library that you prefer, feel free to substitute it for mine. Let's begin with a small example of initializing your adapter, declaring an icon, then displaying it on the screen. Assuming you have already created an icon, that is. If you have not, run ICON286 and have fun creating as many icons as you want. Then try out some of the example programs listed here and the ones that come with ICON286. One more note. I have included a small include file called GRAFINIT.PAS. I use this so I don't have to remember to type all those laborious lines for initializing the drivers and determining which type of adapter I have. To use it simply include it into your pascal file, then call the procedure Grafinit whenever you want to initialize your screen in graphics mode. Program ICON_TEST_ONE; uses (* use the crt unit, the driver unit, the graph unit and icontools *) crt, bgidriv, graph, icontool; var anicon : icon; (* declare ANICON of the object type ICON *) {$I grafinit.pas} (* include the handy screen initializer! *) begin grafinit; (* initialize the graphics adapter, clearing the screen *) (* read in the icon bit mapped image called MYICON, setting - 10 - it's x and y coordinates at the center of the screen. *) anicon.init('','MYICON.ICN',getmaxx div 2, getmaxy div 2); (* check to see if the file was found and the object initialized. *) if anicon.initerror then begin closegraph; restorecrtmode; writeln('Uh oh! There was a problem loading the icon.'); end else begin (* display the icon at the coordinates initially set *) anicon.showicon; (* wait for a key to be pressed *) repeat until keypressed; anicon.hideicon; anicon.disposeicon; end; (* all done *) closegraph; restorecrtmode; end. Let's examine what I've done more closely. First in my program I included the BGIDRIV unit that you can create with borland's BGILINK.PAS file. Then I included borland's graph unit because I needed sme of the functions within the unit, then I included ICONTOOL so I could load and use an icon. The GRAFINIT file, as I explained earlier, is used for convenience when initializing the graphics adapter. You can look at this file to get some hints about linking and using graphics drivers. After calling GRAFINIT to initialize my monitor, I used icon tool's init procedure to get the icon file from disk and initialize it into memory. Let's take a closer look at the parameters. init(iconlib, iconfile : string; startx, starty : integer); The iconlib parameter, though not used in this demonstration, can be used to open a library file created with ILIB, explained later, and load the iconfile specified. For now, though, let's just work with individual icons. The iconfile parameter is a string which will consist of the icon file's name. ICON286 creates two files, and ICN file and ICS file. Do not use the ICS file when specifying an iconfile name because the icontools works only with the bit mapped ICN files. The ICS files are source files and work only with ICON286. The starting X and Y positions are then declared before moving on. The next step is to check and see if the icon was properly loaded and initialized. The INITERROR function returns a boolean value. If the icon has not been loaded properly (which - 11 - can occur if the icon file specified did not exist) then a FALSE is returned. If the initerror function did return a false, then the program closes the graphics adapter, returns to text mode and displays and error message. If the icon was loaded properly then the SHOWICON procedure will display the icon at the initially specified coordinates. Once the icon is displayed the program waits for a key to be pressed before exiting the program. Although hiding the icon and then disposing its memory is unnecessary with such a simple program, I included these procedure anyway to show you how you'd clean up an icon when you were done with it. For example, if you have some sort of a graphical desktop program that uses ICONS for, say, files, then if you were to delete a file, in essence deleting the icon, you'd hide it, dispose of it's memory, then delete the appropriate file that the icon represented. If you had created an icon with a title, the title of the icon should have showed up underneath the icon. This is a feature I included in case you wanted to write that desktop file I mentioned. Then the icon could have an associated filename, or a long description underneath it. You can turn off the title before showing the icon with the following command: anicon.icontitle(false); 4.3 Moving Up to Mouse Support The following demonstration will show you how to load an icon then drag it around with the mouse. There is a more complete example with this package called DRAGICON.PAS, and you may want to compile and play with that one to get used to the things you can do with ICONTOOLS and your mouse. Program DRAG_AN_ICON; uses (* this time we include the mouse unit *) crt, mouse, bgidriv, graph, icontool; var anicon : icon; {$I grafinit.pas } procedure main; var mx, my, mb : word; (* variable for mouse actions *) begin anicon.init('','MYICON.ICN',getmaxx div 2, getmaxy div 2); (* has the icon loaded okay? And is there a mouse? *) if (anicon.initerror) and (not driverinstalled) then begin closegraph; restorecrtmode; writeln('Uh oh! There was a problem loading the icon or you - 12 - have no mouse to speak of.'); end else begin anicon.setput(copyput); (* set the way that icontools draws the object *) anicon.icontitle(false); (* set the borders for where the icon can be dragged. In this case, the entire screen is used. *) anicon.setboundaries(1,1,getmaxx,getmaxy); anicon.showicon; (* reset the mouse, initialize it's X and Y coordinates and display the mouse pointer. *) resetmouse; setmouse(getmaxx div 2, getmaxy div 2); showmouse; repeat getmouse(mx,my,mb); (* get the mouse information *) (* has the first button been pressed? *) if mb=1 then (* if so, check to see if mouse pointer is on the icon *) if anicon.inbounds(mx,my) then begin (* try a different drawing style *) anicon.setput(orput); (* drag the mouse using button 1 while button 1 is pressed down *) anicon.mousedragicon(1); (* this will restore the icons way of drawing back to using copyput, but you must redraw the icon, like such, in order to see its effect. *) hidemouse; anicon.hideicon; anicon.setput(copyput); anicon.showicon; showmouse; end; until b=2; (* repeat until button 2 of mouse is pressed *) mouse.hideicon; mouse.disposeicon; closegraph; restorecrtmode; end; end; begin grafinit; main; (* I like to include a main procedure for my main processing block of code *) end. - 13 - DRAG_AN_ICON is a simple program that shows you how to setup an icon and its physical boundaries in order to drag it around the screen within the boundaries. My personal preference is to use a MAIN procedure called from the initial BEGIN...END. block. This is a good technique in order to minimize global variables. I do all my graphics initialization and other initialization in the BEGIN..END. block, then I call procedure MAIN to handle the dirty work. A close look reveals pretty much the same way of setting up the environment. I used grafinit and initialized an icon, checking to see if it had been properly initialized. I also check to see if a mouse driver is loaded because there's no point in dragging an icon with a mouse if there is no mouse. Then I used a few new procedures. First of all I set the way that the object is drawn on the screen (this is also covered in your Turbo Pascal manuals). I used COPYPUT, but there are a number of choices. You could have used any one of the following: COPYPUT XORPUT ORPUT ANDPUT NOTPUT An experiment: To see what each one of these drawing types does, try placing some different colored and textured boxes on the screen in various places with Turbo Pascal's BAR procedure, then initialize your icon and drag it around the screen, observing what the icon does. Once the drawing technique is set, I tell the object to not include the title when using the icon. I then set the boundaries with the SETBOUNDARIES(startx, starty, endx, endy) procedure. This tells the object to not drag the icon past any one of these boundary points. This is useful when you want to create a widowed type environment and you want the icons to stay within the boundaries of a window. Once the boundaries have been set, I display the icon, then initialize the mouse and display it on the screen where the icon is. Within the Repeat Until loop the mouse is poled for activity, then the MB variable, which holds the button status, is checked. If button one has been pressed, then the mouse's position is checked (using the INBOUNDS procedure) to see if it is within the bounds of the icon. If it is, then I set the mouses drawing style to ORPUT and call the MOUSEDRAGICON routine with the button number, in this case 1. This procedure takes care of the dragging until the button is let go. Once the button has been let go, MOUSEDRAGICON places the icon on its new location, then I reset the drawing method to COPYPUT by hiding the icon, resetting it's drawing method, then redisplaying the icon. When button 2 is pressed the program cleans up the icon memory (again unnecessary, but good practice) and closes the graphics adapter, restoring the crt mode. - 14 - Chapter 5 -- ICON286 Supplementary Tools and Other Programs: 5.1 ICON286 Library Manager The library manager maintains icons that you create with ICON286 in a single, unified library, that can be accessed through ICONTOOLS. The library manager is a command line program run from dos that allows you to create and add icons to a library, extract icons from a library and remove icons from a library. There's also a list feature that will display a directory of the icons within the library. ILIB usage diagram: ILIB [command] [library name] [icon files] ILIB example: ILIB -a icon<.lib> icon1<.icn>+icon2<.icn>+. . . iconN<.icn> These are the command line invocations: -a Add icons to library (this also creates the library if it has not already been created). -d Deletes icons from the library -v, -l Either of these will produce a directory listing -e Extracts icons from the library -x Extracts and then deletes the icons from the library When specifying the icon library name or the actual icons, the extensions are unnecessary. Since all icons created with ICON286 are named with the .ICN extension, and since ILIB gives the .LIB extension to all libraries, you can omit the extensions. They're used in this manual for the sake of clarity. 5.1.1 Using Libraries with ICONTOOLS Libraries are good to have when managing a program that uses lots of different icons. When you develop an application that uses the icons you have created, you'll probably want some way of managing the icons within your directory. Having fifty different icon files in a directory is unprofessional looking at best, so a good way to organize your icons is within a single, unified and manageable file called a library. The ICON object and the ICON MANAGER object have been written to initialize icons either as ICN files or icons within LIB files. When loading an ICN file, the init procedure just looks for the appropriate icon file and loads it into memory. But if a library is specified within the init procedure, ICONTOOLS opens the library file, searches for the icon file specified, and, if it is found, it extracts it from the library - 15 - and into memory. Using either a library or a single icon file will remain transparent to you when developing and to the user when using. Because the ICONTOOLS objects take care of all the low-level dirty work, you won't have to bother with how a library is set up. All you'll have to do is specify whether or not the icon is in a library, which library it's in and what the icon file is called. ICONTOOLS will do all the rest! 5.1.2 Making Libraries for Multiple Video Adapters When developing programs that make use of more than one type of display adapter, multiple libraries can be used with icons that are created in different resolutions. For example, if you were to write some king of shoot-em-up alien space game, you could create a bunch of icons such as ships, aliens, missiles and explosions. Then you could save them in a library and call it GRAFDATA.LIB. But if you were going to write a game that allowed the user of the game to use his or her monitor to its maximum resolution and color, then you could, if you had, a VGA, load the icon source files in different graphics modes and save them again thus creating ICN files for that particular mode and resolution. You could then create a library called CGADATA.LIB. You could do a library for each type of monitor, i.e. EGADATA.LIB, VGADATA.LIB, HERCDATA.LIB, then in your program you could load the appropriate library according the graphics adapter the person has in his system. 5.2 Using CNVICON.EXE CNVICON.EXE will convert ICS files to ICN files for the highest resolution that the video adapter in the current computer is capable of. For example; In my ALIEN game that I have created, I include all the ICS files. Before you run the game your are told, in the accompanying documentation, to run the CONVERT batch file. All this does is load all the ICS files, one at a time, and creates ICN files in your highest resolution. Then you can play the game once the ICN files have been created. You can use wildcard parameters with CNVICON when converting ICS files. For example: CNVICON *.ICS will convert all the ICS files in a subdirectory to their appropriate ICN files. CNVICON ALIEN*.ICS will convert all the ALIEN source files to ALIEN bit mapped icon files. You can have a batch file that automates, for the user, a way of setting up icons for his system and storing them in a library. In case you don't have the convenience of a VGA for creating separate distribution Libraries, you could supply the source files and a SETUP batch file that converts all the necessary icon source files to their bit mapped components, - 16 - creates a library of the ICN files, then deletes the ICN files. It wouldn't be the most professional way, but it would be convenient and a one-time-only thing. Once the library for the particular user is created, he need only run the application. 5.3 Make Animation Libraries Because icon libraries are just a sequence of icons, you could draw a sequence of frames of, say, a stick man walking. You could call each frame MAN#, where # is an actual number. Then you could save each of those icons to a library, use the library manager to load the entire library, then display each icon in sequence giving the appearance of a man walking along the screen. ANIMAT.PAS is a program that will test an animation library if you decide to create one. Check out the source to see how I did it, then create some kind of animation library and run it with ANIMAT. There's all kinds of possibilities with simple animation. The ALIEN game that I have included works with animation. Whenever you or the alien gets hit with a missile, a sequence of frames depict the explosion presenting the illusion of either the ship or the alien being destroyed. I used only a few frames to make simple explosions, but you can get as detailed as you'd like. Remember, once the icons are loaded, there's no more going back to slow disk accesses. Using animation sequences is all done from memory, so the appearance of animation should be fast. In fact you might have to add a delay in order to see what's happening. 5.4 TLIST the File Lister In case you were wondering about this little program and if it costs anything, don't wonder any longer. I include TLIST with all my software so users of my software can browse the accompanying documentation on-line, and even print it when ready. I created this program with an early version of Turbo Pascal (after 3 since it is an EXE file) and have used it ever since. It's yours to keep and if you find it useful then by all means use it. And pass it around to anyone else who might want to use it. There are no search facilities or any of the other niceties that some of those more advanced file viewers contain, but it's good enough to view straight ASCII files. You can scroll up and down as well as left and right. You can advance straight to the top or go down to the bottom. And you can use the print service to print the file. TLIST is a memory only file viewer. That is, once the file exceeds the memory limit of your system, then there will be no more room to view the rest. At this point TLIST asks you if you still want to view the file despite the fact that it couldn't load the entire file. I find that all my documentation as well as most other documentation from other shareware packages fits neatly into 640K, so I have little problem loading an viewing files. - 17 - If TLIST should cause your system to crash for any reason, then please notify me. I've been testing it for years and there has been no indication of it crashing systems or destroying files, but in case something weird happens to you while using it, don't hesitate in letting me know. - 18 - Chapter 6 -- CLOSING NOTES/TECHNICAL STUFF 6.1 Closing Notes I hope that this program benefits you in some way. If it does, and if you use it to create programs that are freeware, shareware or commercial, I would appreciate you taking the time to fill out the user registration form and to send in a check or money order to SofDesign's address above. I ask a fee of $49.95 which I think is a modest sum for both an editor, programming tools and source code. The registration fee is also an incentive for me to keep refining and adding to ICONDRAW and ICONTOOLS, and also to keep refining this documentation. Any questions, comments or suggestions can be directed to me, Tom Clancy, at SofDesign Technology. The address and phone number are stated here: SofDesign Technology C/O Tom Clancy 58 North Dillon St. Titusville, PA 16354-2406 Phone Number: (814) 827-2306 6.2 Future Notes This is only the first version of this software, but I hope to keep programming and refining it and, with your help and suggestions, adding features that make using icons easier. I am planning to refine the ICONDRAW interface as soon as I get a computer with VGA graphics and a much faster processor. Not that the processor will make any difference to the look of the product, but it will sure cut down the time between compilations. Because there seems to be so many C++ programmers out there these days, I'm plannning a C++ set of ICON TOOLS for them, and I might create the new ICON DRAW interface in Borland's C++. I love Turbo Pascal and all it can do with objects, but C++, I find, is more flexible and faster in some cases. So if you like this program and are considering a move to C++, don't worry. I will have ICONDRAW compatible C++ libraries out soon. As far as the libraries are concerened, I plan to extend them even more, adding an event driven desktop that will allow you to mix icons and graphical windows as well as dialogue boxes and user prompts. I'm going to eventually combine all my tools into one set of graphical programming tools for both Turbo Pascal and Turbo C++. - 19 -